HTTP API

Zur Verwendung der HTTP API benötigen Sie zunächst einen Systembenutzer, der über die Berechtigung zur Nutzung der API verfügt.

ê Wir empfehlen dafür nicht den Benutzer "admin" zu verwenden, sondern einen neuen Benutzer mit eingeschränkten Berechtigungen zu erstellen.

1Anlegen eines neuen Systembenutzers

Melden Sie sich mit dem Benutzer admin am SMS Gateway an
Navigieren Sie über Konfiguration in der Menüleiste zum Punkt Systembenutzer
Erstellen Sie einen neuen Benutzer, z.B.: apiuser
Verwalten Sie die Berechtigungen des Benutzers über das Stift Symbol am Ende der Zeile
Erteilen Sie die Berechtigung Zugriff auf die HTTP API
Weitere Berechtigungen werden nicht benötigt

2Verwendung der HTTP API

Die API kann über die folgenden Adresse angesprochen werden: https://<SMS Gateway IP>/api.php

An diese Schnittstelle können Sie via POST oder GET Daten übergeben.

Notwendig

Option	Beschreibung
username	Systembenutzer, der die Berechtigung zum Zugriff auf die HTTP API besitzt
password	Das zum Benutzer gehörige Passwort
text	Inhalt der SMS
to	Empfänger der SMS, abhängig von mode

Optional

Option

Beschreibung

hexmode

Mit true kann der Text in Hexadezimalem Format an die API übergeben werden. Standard ist false.

list

Mit white wird eine Whitelist definiert, mit black wird eine Blacklist definiert. Benötigt den zusätzlichen Parameter regex.

mode

Modus, entspricht der nachfolgenden Tabelle. Bei ungültigem Modus wird die Nachricht mittels number versendet.

Option	Bedeutung to	Beschreibung
Gruppe	to = ID (empfohlen) oder Name einer Benutzergruppe	Mit dieser Option können sie eine SMS an eine Benutzergruppe versenden. Benutzergruppen werden über Konfiguration - Gruppen verwaltet. Die Verwendung von Gruppen erfordert die Lizenzierung des Moduls Empfängergruppen.
number	to = Telefonnummer des Empfängers	Mit dieser Option können Sie eine SMS an eine einzelne Telefonnummer versenden. (Standard)
telgroup	to = ID (empfohlen) oder Name einer Benutzergruppe	Mit dieser Option können sie eine Nachricht mittels Automatik an eine Benutzergruppe versenden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt. Benutzergruppen werden über Konfiguration - Gruppen verwaltet. Die Verwendung von Gruppen erfordert die Lizenzierung des Moduls Empfängergruppen.
telnumber	to = Telefonnummer des Empfängers	Mit dieser Option können Sie eine Nachricht mittels Automatik an eine einzelne Telefonnummer versenden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt.
teluser	to = ID (empfohlen) oder Name eines Kontakts aus dem Adressbuch	Mit dieser Option können sie eine Nachricht mittels Automatik an einen Kontakt senden. Bei Automatik wird zunächst versucht die Benachrichtigung per Telegram zu versenden, schlägt dies fehl wird per SMS benachrichtigt. Kontakte werden über Konfiguration - Adressbuch verwaltet.
user	to = ID (empfohlen) oder Name eines Kontakts aus dem Adressbuch	Mit dieser Option können sie eine SMS an einen Kontakt senden. Kontakte werden über Konfiguration - Adressbuch verwaltet.

regex

Hier kann eine Regular Expression übergeben werden. Falls diese auf die verwendet Absendernummer zutreffen sollte, wird mit list definiert ob die Absendernummer abgelehnt oder akzeptiert wird. Bitte beachten Sie eine möglicherweise notwendige URL-Enkodierung.

telauto

Mit false kann die Automatik-Option abgeschaltet werden. Wenn dies nicht deaktiviert ist, wird die Nachricht per SMS gesendet, wenn die Nummer des Empfängers nicht für das Telegramm verwendet wurde.

3 Fehlerrückgabe

HTTP Status Code	Fehlerausgabe	Beschreibung
400	Error. See Gateway logs for more information.	Falscher Modus ausgewählt, Gruppe nicht vorhanden, Kontakt nicht vorhanden, Fehlerhafte Nummer
400	Error: Parameter miss	Fehlende Parameter
401	401 Unauthorized - Username or Password wrong	Username und/oder Passwort falsch eingegeben
403	403 Forbidden - Your User has no right to send SMS over API	Der User hat keine Berechtigung SMS über die API zu versenden
408	FAILED - Timeout or see Gateway logs for more information.	Der Server hat das Zeitlimit überschritten und auf Anforderungen gewartet

i Die Fehlercodes werden zusätzlich als HTTP-Response-Code ausgegeben.

4 Beispiele mit GET

Beispiel SMS

curl

curl -X GET "https://<IP des SMS Gateways>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=number"

powershell

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=number" -Method GET

Beispiel Telegram

curl

curl -X GET "https://<IP des SMS Gateways>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false"

powershell

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false" -Method GET

Beispiel Hexmode

curl

curl -X GET "https://<IP des SMS Gateways>/api.php?text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true"

powershell

Invoke-WebRequest -Uri "https://<IP SMS Gateway>/api.php?text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true" -Method GET

5 Beispiele mit POST

Beispiel SMS

curl

curl -X POST -d "text=Test&to=00491701234567&username=apiuser&password=secret&mode=number" "https://<IP des SMS Gateways>/api.php"

powershell

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='Test';mode='number'}

Beispiel Telegram

curl

curl -X POST -d "text=Test&to=00491701234567&username=apiuser&password=secret&mode=telnumber&telauto=false" "https://<IP des SMS Gateways>/api.php"

powershell

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='Test';mode='telnumber';telauto='false'}

Beispiel Hexmode

curl

curl -X POST -d "text=48616c6c6f2064696573206973742065696e65205465737420534d53&to=00491701234567&username=apiuser&password=secret&hexmode=true" "https://<IP des SMS Gateways>/api.php"

powershell

Invoke-WebRequest -Uri https://<IP SMS Gateway>/api.php -Method POST -Body @{username='apiuser';password='secret';to='01701234567';text='48616c6c6f2064696573206973742065696e65205465737420534d53';hexmode='true'}

❕URL encoding

Einige Sonderzeichen und Leerzeichen können ohne URL-Encoding nicht über die HTTP API versendet werden. Verwenden Sie die Prozentdarstellung, um den Inhalt Ihrer Nachricht zu kodieren.

Verwandte Artikel